Category: new-feature
Tracking: #8591
User impact: Goose2 can render MCP apps inline and let users interact with them directly in the chat timeline.

Summary
This PR turns the MCP app payload that Goose2 already receives from tool results into a real inline app view. Apps are loaded through a local double-iframe sandbox proxy, initialized with Goose2 host context, and connected back to Goose through the MCP app bridge.

The result is that users can run an MCP tool, see its app UI inline, click controls inside that UI, and have those interactions route back through the current Goose session.

MCP App Bench demo

real-world MCP App demo (agentic commerce)

What Reviewers Should Look For

• Inline rendering: MCP app HTML is hydrated into McpAppView and hosted in a sandboxed iframe instead of being shown as raw data.
• App bridge behavior: app-originated messages, nested tool calls, resource reads, link opens, and resize notifications route through Goose2 and Goose serve.
• State preservation: live updates and replay keep the MCP app payload attached to the correct assistant message.
• Theme and layout polish: theme changes update host context without remounting the app, transparent iframes match light/dark mode, and the inline app/composer boundary behaves cleanly.
• Structured output: structured tool content remains visible and inspectable in the normal tool-result UI.
• Generated/API surface: ACP schema, SDK output, and Goose2 dependency lockfile changes are included for the new bridge/proxy surface.

How Inline Apps Load

sequenceDiagram
    participant User
    participant Goose2
    participant Renderer as McpAppView / AppRenderer
    participant GooseServer as Goose server
    participant MCPServer as MCP server
    participant Proxy as Trusted proxy (/mcp-app-proxy)
    participant Guest as Guest origin (/mcp-app-guest)

    User->>Goose2: Send prompt
    Goose2->>GooseServer: Continue session with prompt
    GooseServer->>GooseServer: Decide to call MCP tool
    GooseServer->>MCPServer: Call selected tool
    MCPServer-->>GooseServer: Tool result with app resource metadata
    GooseServer->>MCPServer: Read app resource
    MCPServer-->>GooseServer: HTML, CSP, and UI metadata
    GooseServer-->>Goose2: Assistant update with MCP app payload
    Goose2->>Goose2: Normalize MCP app CSP metadata
    Goose2->>Renderer: Render inline app payload
    Renderer->>GooseServer: Request local app host info
    GooseServer-->>Renderer: Proxy base URL and secret
    Note over Renderer,GooseServer: Inline apps require a local ws/http serve origin. Secure serve URLs fail closed for now.
    Renderer->>Proxy: Load trusted outer proxy with app HTML, CSP, and secret
    Proxy->>Proxy: Verify secret and loopback peer
    Proxy->>Proxy: Store guest HTML and CSP
    Proxy->>Guest: Create sandboxed guest iframe
    Guest->>Proxy: Fetch stored guest HTML
    Proxy->>Proxy: Verify secret and loopback peer
    Proxy-->>Guest: Serve isolated app HTML
    Guest-->>Renderer: Initialize with tool data and host context

McpAppView is the Goose2 React wrapper that renders the @mcp-ui/client AppRenderer. Goose serves a trusted outer proxy at /mcp-app-proxy; that proxy stores the app document and loads it from a separate loopback guest origin at /mcp-app-guest, preserving the sandbox while keeping guest HTML off the Goose/ACP origin.

Bridge Paths Covered

• ui/message: sends a normal user message through the existing Goose2 chat flow.
• tools/call: calls an app-visible tool through _goose/tool/call without replacing the original app tool result.
• resources/read: reads resources for the same session and extension through ACP.
• ui/open-link: validates http/https links and asks the user to confirm before opening through the native shell.
• ui/notifications/size-changed: resizes the inline frame and preserves sticky scroll behavior.
• ui/notifications/host-context-changed: keeps the already-mounted app aligned with host theme and container changes.

Bridge Message Sequences
Any UI element in the embedded app, such as a button, can initiate these JSON-RPC bridge requests. Host notifications use the same bridge back into the already-mounted app.

ui/message

sequenceDiagram
    participant App as MCP app iframe
    participant Renderer as McpAppView AppRenderer
    participant Chat as Goose2 chat submit
    participant GooseServer as Goose server

    App->>Renderer: ui/message
    Renderer->>Chat: Submit as user message
    Chat->>GooseServer: Continue the same session
    GooseServer-->>Chat: Stream assistant updates
    Chat-->>Renderer: Update timeline

tools/call

sequenceDiagram
    participant App as MCP app iframe
    participant Renderer as McpAppView AppRenderer
    participant GooseServer as Goose server

    App->>Renderer: tools/call
    Renderer->>GooseServer: _goose/tool/call
    GooseServer-->>Renderer: Tool result
    Renderer-->>App: Resolve tool call

resources/read

sequenceDiagram
    participant App as MCP app iframe
    participant Renderer as McpAppView AppRenderer
    participant GooseServer as Goose server

    App->>Renderer: resources/read
    Renderer->>GooseServer: _goose/resource/read
    GooseServer-->>Renderer: Resource contents
    Renderer-->>App: Resolve resource read

ui/open-link

sequenceDiagram
    participant User
    participant App as MCP app iframe
    participant Renderer as McpAppView AppRenderer
    participant Modal as LinkSafetyModal
    participant Shell as Native shell

    User->>App: Click link or button
    App->>Renderer: ui/open-link with URL
    Renderer->>Renderer: Allow http and https only
    alt Allowed URL
        Renderer->>Modal: Show confirmation
        alt User confirms
            User->>Modal: Open link
            Modal-->>Renderer: Confirm
            Renderer->>Shell: Open URL
            Renderer-->>App: Return success
        else User cancels
            User->>Modal: Cancel
            Modal-->>Renderer: Cancel
            Renderer-->>App: Return error
        end
    else Blocked scheme
        Renderer-->>App: Return error
    end

ui/notifications/size-changed

sequenceDiagram
    participant App as MCP app iframe
    participant Renderer as McpAppView AppRenderer

    App->>Renderer: ui/notifications/size-changed
    Renderer->>Renderer: Update iframe height
    Renderer->>Renderer: Preserve sticky scroll when pinned

ui/notifications/host-context-changed

sequenceDiagram
    participant Renderer as McpAppView AppRenderer
    participant App as MCP app iframe

    Renderer->>Renderer: Recompute host context
    Renderer-->>App: ui/notifications/host-context-changed

Goose2 chat submit is the existing chat submission/session continuation path used by the composer; the app bridge reuses it for ui/message. LinkSafetyModal is the Goose2 confirmation UI shown before the native shell opens app-requested links.

Manual Validation
MCP AppBench server URL: https://mcp-app-bench.onrender.com/mcp

Suggested prompts after adding the server to Goose2:

1. run the app bench messaging inspector.
2. run the app bench host info inspector.
3. run the app bench tool data inspector.
4. run the app bench display modes inspector.
5. run the app bench transparency inspector.

In the Messaging Inspector, click:

• ui/message: a new user message should appear in Goose2.
• tools/call: a nested tool result should return inside the app without clearing the original app footer or structured output.
• resources/read: the demo resource should return through the session-scoped resource path.
• ui/open-link: Goose2 should show the link-safety modal; confirming opens the URL, while canceling returns an error to the app.
• ui/notifications/size-changed: the frame should resize and stay pinned when the user is already at the bottom.
• notifications/message and ping: the app/server messaging path should complete successfully.

Visual checks:

• Switch Goose2 between light and dark after an app is already loaded. The app should stay rendered, and the reported host theme should match Goose2.
• In the Transparency Inspector, transparent areas should show the Goose2 chat background in both light and dark mode.
• Bordered apps should get border/radius chrome. Borderless apps should not get border, radius, shadow, or extra chrome.
• The app frame should sit naturally in the message column, and the chat input should not overlap loading labels such as Reasoning.

Not In Scope Yet
This PR establishes a working inline MCP app host, but it is not full MCP Apps conformance.

Likely follow-ups:

• Fill out more of hostContext, especially the broader optional fields in Host Context in McpUiInitializeResult.
• Add display mode handling beyond inline, including fullscreen and picture-in-picture.
• Implement ui/update-model-context so apps can update model context for future turns.
• Explore HTTPS or a stronger secured-origin model for the local proxy.